// Copyright (c) 2010, Anthony Cassidy
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without modification, are 
// permitted provided that the following conditions are met:
// 
//     * Redistributions of source code must retain the above copyright notice, this list 
//         of conditions and the following disclaimer.
//     * Redistributions in binary form must reproduce the above copyright notice, this 
//         list of conditions and the following disclaimer in the documentation and/or 
//         other materials provided with the distribution.
//     * Neither the name of the AntsAdventureGameCreator nor the names of its contributors 
//         may be used to endorse or promote products derived from this software without 
//         specific prior written permission.
// 
// 
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 
// OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT 
// SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
// SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
// CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.

/*!
@page Example1
<h1>Example 1 - Composing a room </h1>
<img src="Example1.png">
<h2> Summary </h2>
This example shows how to set up folders to compose a room.

<h2>Steps</h2>
<ol>
<li>
Run the prebuilt Example1.exe in the Example1 folder.

</li>
<li>
Hit space (or middle click the mouse) and choose "Switch To Room ..."
<img src="Example1_1.png" halign="left">
</li>
<li>
Browse to the 'example1' folder and click ok.
</li>
</ol>

The exe knew how to draw the room by the way
it was arranged in the folders.
What follows is a description of how
the renderer draws the scene.


<h2> Folder structure of a room</h2>
All the graphics for a single Room
are contained in a single folder
dedicated to that room: the room folder.
By default, the Room renderer renders
a Room by rendering the first
PNG image in each subfolder of
the room folder, one over the top
of each other, at screen location (0,0).

Every element in the scene 
(including the background,
and main character)  
is rendered in this way.

Each element that is rendered
this way (including the background,
and main character) is called a RoomObject.

<img src = "Example1_2.png">

When the user hovers their mouse over the scene, the name of the 
item that is under the mouse will appear in the CommandLine.
By default, the name of the item is the name of the folder its 
graphics are from, however you can change what appears on the 
command line by calling using the API method 
RoomObject::SetDisplayName. 

You can change the order that rooms are rendered in by 
calling the API method RoomObject::SetOrderingNumber.
Higher numbers are rendered over the top of lower numbers.
If a folder name is prefixed by a number, then the RoomObject
will have its OrderingNumber set to this value.

The Room name can also be isolated by enclosing it in a pair of 
parenthesis/brackets. In this case everything before the 
first bracket and after the last bracket is ignored.

<h2>Image requirements</h2>
All images must use PNG alpha to determine 
which parts see through to the object 
behind them. This allows the renderer to render images
on top of each other.

<h2>Three ways to prevent an object being rendered</h2>
The most common way is to use the script method 
RoomObject::SetVisible false (this is covered in @ref Example5).
This is usually done when the Room is initialized, whereby the 
IEventHandlers::OnInitializeRoom is called (this is covered in @ref Example3)

The Room renderer also ignores two types of folders. These are folders that:
- are prefixed with "inv_"
- contain a comma

The former are used for InventoryItems (covered in @ref Example5 ).
The latter are used to define Animations (covered in A @ref Example4 ).

<h2> Image reuse </h2>
It is very probable that two separate rooms may need to share 
the same images (of the character walking, for example).
This can be done by copying the shared folders of images,
but this means that updating the images will need to be done
in more than one location. A better way is to use Resource Rooms
(covered in @ref Example9 )

<h2> Going further </h2>
To specify the interactions that can occur in that room,
C++ must be used to create executable code.
Examples of how to do this can be found in @ref Example3.

<br>
<br>
On to @ref Example2...
*/

